import { PackageManagerTabs } from '@theme';
import { Stability } from '@components/ApiMeta.tsx';

# React

## How to use

Rspack provides two solutions to support React:

- **Use Rsbuild**: Rsbuild provides out-of-the-box support for React, allowing you to quickly create a React project. See [Rsbuild - React](https://rsbuild.rs/guide/framework/react) for details.
- **Manual configure Rspack**: You can refer to the current document to manually add configurations for React.

## Configure JSX/TSX

Rspack leverages SWC transformer for supporting JSX and TSX.

You can add [builtin:swc-loader](/guide/features/builtin-swc-loader) loader to support `.jsx` and `.tsx` files:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.jsx$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              parser: {
                syntax: 'ecmascript',
                jsx: true,
              },
            },
          },
        },
        type: 'javascript/auto',
      },
      {
        test: /\.tsx$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              parser: {
                syntax: 'typescript',
                tsx: true,
              },
            },
          },
        },
        type: 'javascript/auto',
      },
    ],
  },
};
```

Refer to [builtin:swc-loader](/guide/features/builtin-swc-loader) for detailed configurations.

## Fast Refresh

There are currently two ways to enable React Fast Refresh in Rspack:

First you need to install [@rspack/plugin-react-refresh](https://www.npmjs.com/package/@rspack/plugin-react-refresh) to support React Fast Refresh.

<PackageManagerTabs command="add @rspack/plugin-react-refresh react-refresh -D" />

Enabling [React Fast Refresh](https://reactnative.dev/docs/fast-refresh) functionality primarily involves two aspects: code injection and code transformation.

- Code injection will inject some code from the `react-refresh` package, as well as some custom runtime code, all of which are integrated in the [@rspack/plugin-react-refresh](https://github.com/rspack-contrib/rspack-plugin-react-refresh) plugin and can be injected through this plugin.
- Code transformation can be added through loaders, such as [jsc.transform.react.refresh](https://swc.rs/docs/configuration/compilation#jsctransformreactrefresh) for swc-loader or the [react-refresh/babel](https://github.com/facebook/react/tree/main/packages/react-refresh) for babel-loader.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';
import ReactRefreshPlugin from '@rspack/plugin-react-refresh';

const isDev = process.env.NODE_ENV === 'development';

export default {
  // ...
  mode: isDev ? 'development' : 'production',
  module: {
    rules: [
      {
        test: /\.jsx$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              parser: {
                syntax: 'ecmascript',
                jsx: true,
              },
              transform: {
                react: {
                  development: isDev,
                  refresh: isDev,
                },
              },
            },
          },
        },
      },
    ],
  },
  plugins: [
    isDev && new ReactRefreshPlugin(),
    isDev && new rspack.HotModuleReplacementPlugin(),
  ],
};
```

Compared to the previous approach, this method decouples the React Fast Refresh code injection logic from the transformation logic. The code injection logic is handled uniformly by the @rspack/plugin-react-refresh plugin, while the code transformation is handled by loaders. This means that this plugin can be used in conjunction with `builtin:swc-loader`, `swc-loader`, or `babel-loader`:

- For usage with `builtin:swc-loader`, you can refer to the example at [examples/react-refresh](https://github.com/rspack-contrib/rstack-examples/tree/main/rspack/react-refresh), When using with `swc-loader`, simply replace `builtin:swc-loader` with `swc-loader`.
- For usage with `babel-loader`, you can refer to the example at [examples/react-refresh-babel-loader](https://github.com/rspack-contrib/rstack-examples/tree/main/rspack/react-refresh-babel-loader)

## React Compiler

React Compiler is an experimental compiler introduced in React 19 that can automatically optimize your React code.

Before you start using React Compiler, it's recommended to read the [React Compiler documentation](https://react.dev/learn/react-compiler) to understand the functionality, current state, and usage of the React Compiler.

:::tip
At present, React Compiler only supports Babel compilation, which may slow down the build time.
:::

### How to use

The steps to use React Compiler in Rspack:

1. Upgrade versions of `react` and `react-dom` to 19. If you are unable to upgrade, you can install the extra [react-compiler-runtime](https://www.npmjs.com/package/react-compiler-runtime) package which will allow the compiled code to run on versions prior to 19.
2. React Compiler currently only provides a Babel plugin, you need to install:

- [@babel/core](https://www.npmjs.com/package/@babel/core)
- [babel-loader](https://www.npmjs.com/package/babel-loader)
- [babel-plugin-react-compiler](https://www.npmjs.com/package/babel-plugin-react-compiler)
- [@babel/plugin-syntax-jsx](https://www.npmjs.com/package/@babel/plugin-syntax-jsx)

3. Register `babel-loader` in your Rspack config file:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: [
          {
            loader: 'builtin:swc-loader',
            options: {
              // SWC options for JS
            },
          },
        ],
      },
      {
        test: /\.jsx$/,
        use: [
          {
            loader: 'builtin:swc-loader',
            options: {
              // SWC options for JSX
            },
          },
          { loader: 'babel-loader' },
        ],
      },
    ],
  },
};
```

4. Create a `babel.config.js` and configure the plugins:

```js title="babel.config.js"
const ReactCompilerConfig = {
  /* ... */
};

module.exports = function () {
  return {
    plugins: [
      ['babel-plugin-react-compiler', ReactCompilerConfig], // must run first!
      '@babel/plugin-syntax-jsx',
    ],
  };
};
```

For React 17 and 18 projects, you need to install [react-compiler-runtime](https://www.npmjs.com/package/react-compiler-runtime) and specify the `target`:

```js title="babel.config.js"
const ReactCompilerConfig = {
  target: '18', // '17' | '18' | '19'
};
```

### Examples

You can refer to the following example projects:

- [Rspack + React Compiler](https://github.com/rspack-contrib/rstack-examples/tree/main/rspack/react-compiler-babel)
- [Rspack + React Compiler + TypeScript](https://github.com/rspack-contrib/rstack-examples/tree/main/rspack/react-compiler-babel-ts)

## Integrating SVGR

[SVGR](https://react-svgr.com/) is an universal tool for transforming [Scalable Vector Graphics (SVG)](https://en.wikipedia.org/wiki/SVG) files into React components.

The usage of SVGR with Rspack is exactly the same as with Webpack.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.svg$/i,
        issuer: /\.[jt]sx?$/,
        use: ['@svgr/webpack'],
      },
    ],
  },
};
```

For detailed usage of SVGR, please refer to [SVGR Documentation - webpack](https://react-svgr.com/docs/webpack/).
